|
|
OpenCPicture |
||||
| Header: | Quickdraw.h | Carbon status: | Supported | |
Begins defining a picture in extended version 2 format.
PicHandle OpenCPicture (
const OpenCPicParams *newHeader
);
An OpenCPicParams structure.
A handle to a new Picture structure. OpenCPicture collects your subsequent drawing commands in this structure. Use this handle when referring to the picture in subsequent functions, such as the DrawPicture function.
When defining a picture, you can use all other QuickDraw drawing functions, with the exception of CopyMask, CopyDeepMask, SeedFill, SeedCFill, CalcMask, and CalcCMask. You can also use the PicComment function to include picture comments in your picture definition.
The OpenCPicture function creates a pictures in the extended version 2 format. This format permits your application to specify resolutions when creating images.
Use the OpenCPicParams structure you pass in the newHeader parameter to specify the horizontal and vertical resolution for the picture, and specify an optimal bounding rectangle for displaying the picture at this resolution. When you later call the DrawPicture function to play back the saved picture, supply a destination rectangle, and DrawPicture scales the picture so that it is completely aligned with the destination rectangle. To display a picture at a resolution other than that at which it was created, compute an appropriate destination rectangle by scaling its width and height by the following factor:
scale factor = destination resolution / source resolution
For example, if a picture was created at 300 dpi and you want to display it at 75 dpi, then your application should compute the destination rectangle width and height as 1/4 of those of the picture’s bounding rectangle.
The OpenCPicture function calls the HidePen function, so no drawing occurs on the screen while the picture is open (unless you call the ShowPen function just after OpenCPicture, or you called ShowPen previously without balancing it by a call to HidePen).
After defining the picture, close it by using the ClosePicture function.
After creating the picture, use the GetPictInfo function to gather information about it. The PictInfo structure returned by GetPictInfo returns the picture’s resolution and optimal bounding rectangle.
When creating a picture, use the ClosePicture function to finish it before you open the Printing Manager with the PrOpen function. There are two main reasons for this. First, you should allow the printing driver to use as much memory as possible. Second, the Printing Manager creates its own type of graphics port, one that replaces the standard QuickDraw drawing operations stored in the grafProcs field of a CGrafPort or GrafPort structure. To avoid unexpected results when creating a picture, draw into a graphics port created with QuickDraw instead of drawing into a printing port created by the Printing Manager.
After calling OpenCPicture, be sure to finish your picture definition by calling ClosePicture before you call OpenCPicture again. You cannot nest calls to OpenCPicture.
Always use the ClipRect procedure to specify a clipping region appropriate for your picture before you call OpenCPicture. If you do not use ClipRect to specify a clipping region, OpenCPicture uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you scale the picture when drawing it, the clipping region can become invalid when DrawPicture scales the clipping region—in which case, your picture will not be drawn.
The OpenCPicture function may move or purge memory; do not call at interrupt time.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)